extract-files

What is extract-files?

The extract-files package is designed to extract files from a JavaScript object tree so they can be uploaded via a multipart request. It is commonly used in applications that need to handle file uploads, especially in the context of GraphQL operations.

What are extract-files's main functionalities?

Extract files from an object

This feature allows you to extract files from an object, which is useful when preparing files for upload. The `extractFiles` function takes an object and a path to traverse within the object to find files. It returns an object with the extracted files and a clone of the original object with files replaced by null.

{"operation": "const { extractFiles } = require('extract-files');\nconst file = new File(['content'], 'file.txt', { type: 'text/plain' });\nconst operation = { variables: { file } };\nconst { files, clone } = extractFiles(operation, 'variables');"}

Support for FileList and Map objects

The package can handle `FileList` objects, which are typically obtained from file input elements, and `Map` objects. It can extract files from these complex structures, making it versatile for various file upload scenarios.

{"operation": "const { extractFiles } = require('extract-files');\nconst fileList = document.querySelector('input[type=file]').files;\nconst operation = { variables: { files: fileList } };\nconst { files, clone } = extractFiles(operation, 'variables');"}

Other packages similar to extract-files

form-data

The form-data package allows you to create `multipart/form-data` streams to submit files and values via HTTP. It can be used to simulate a form submission with file uploads, similar to extract-files, but it is more focused on constructing the form data itself rather than extracting files from an existing object structure.

busboy

Busboy is a Node.js module for parsing incoming HTML form data, including file uploads. It differs from extract-files in that it is used on the server side to process file uploads, whereas extract-files is typically used on the client side to prepare files for upload.

multer

Multer is a Node.js middleware for handling `multipart/form-data`, primarily used for uploading files. It is similar to busboy but is designed to be used with Express applications. Unlike extract-files, multer is not about extracting files from an object but rather about handling file uploads on the server side.

README

extract-files

Clones a value, recursively extracting File, Blob and ReactNativeFile instances with their object paths, replacing them with null. FileList instances are treated as File instance arrays.

Used by GraphQL multipart request spec client implementations such as graphql-react and apollo-upload-client.

Usage

Install with npm:

npm install extract-files

See the extractFiles documentation to get started.

Support

• Node.js v8.10+
• Browsers > 0.5%, not OperaMini all, not dead
• React Native

API

Table of contents

• class ReactNativeFile
• function extractFiles
• function isExtractableFile
• type ExtractableFile
• type ExtractableFileMatcher
• type ExtractFilesResult
• type ObjectPath
• type ReactNativeFileSubstitute

class ReactNativeFile

Used to mark a React Native File substitute in an object tree for extractFiles. It’s too risky to assume all objects with uri, type and name properties are files to extract.

Parameter	Type	Description
file	ReactNativeFileSubstitute	A React Native File substitute.

Examples

An extractable file in React Native.

import { ReactNativeFile } from 'extract-files'

const file = new ReactNativeFile({
  uri: uriFromCameraRoll,
  name: 'a.jpg',
  type: 'image/jpeg'
})

---

function extractFiles

Clones a value, recursively extracting File, Blob and ReactNativeFile instances with their object paths, replacing them with null. FileList instances are treated as File instance arrays.

Parameter	Type	Description
value	*	Value (typically an object tree) to extract files from.
path	ObjectPath? = ''	Prefix for object paths for extracted files.
isExtractableFile	ExtractableFileMatcher? = isExtractableFile	The function used to identify extractable files.

Returns: ExtractFilesResult — Result.

Examples

Extract files from an object.

For the following:

import { extractFiles } from 'extract-files'

const file1 = new File(['1'], '1.txt', { type: 'text/plain' })
const file2 = new File(['2'], '2.txt', { type: 'text/plain' })
const value = {
  a: file1,
  b: [file1, file2]
}

const { clone, files } = extractFiles(value, 'prefix')

value remains the same.

clone is:

{
  a: null,
  b: [null, null]
}

files is a Map instance containing:

Key	Value
file1	['prefix.a', 'prefix.b.0']
file2	['prefix.b.1']

---

function isExtractableFile

Checks if a value is an extractable file.

Type: ExtractableFileMatcher

Parameter	Type	Description
value	*	Value to check.

Returns: boolean — Is the value an extractable file.

Examples

How to import.

import { isExtractableFile } from 'extract-files'

---

type ExtractableFile

An extractable file.

Type: File | Blob | ReactNativeFile

---

type ExtractableFileMatcher

A function that checks if a value is an extractable file.

Type: Function

Parameter	Type	Description
value	*	Value to check.

Returns: boolean — Is the value an extractable file.

See

• isExtractableFile is the default extractable file matcher.

Examples

How to check for the default exactable files, as well as a custom type of file.

import { isExtractableFile } from 'extract-files'

const isExtractableFileEnhanced = value =>
  isExtractableFile(value) ||
  (typeof CustomFile !== 'undefined' && value instanceof CustomFile)

---

type ExtractFilesResult

What extractFiles returns.

Type: object

Property	Type	Description
clone	*	Clone of the original input value with files recursively replaced with null.
files	Map<ExtractableFile, Array<ObjectPath>>	Extracted files and their locations within the original value.

---

type ObjectPath

String notation for the path to a node in an object tree.

Type: string

See

• object-path on npm.

Examples

Object path is property a, array index 0, object property b.

a.0.b

---

type ReactNativeFileSubstitute

A React Native File substitute for when using FormData.

Type: object

Property	Type	Description
uri	string	Filesystem path.
name	string?	File name.
type	string?	File content type.

See

• React Native FormData polyfill source.

Examples

A camera roll file.

{
  uri: uriFromCameraRoll,
  name: 'a.jpg',
  type: 'image/jpeg'
}

Changelog

6.0.0

Major

• Updated Node.js support from v6+ to v8.10+.

Minor

• Added the ability to customize what are extractable files, fixing #10 via #11:
  • Added a new third parameter to the extractFiles function, for specifying a custom extractable file matcher.
  • Export a new isExtractableFile function that is used as the default extractable file matcher for the extractFiles function. This can be used in a custom extractable file matcher implementation to match the default extractable files, along with additional custom files.
• Setup GitHub Sponsors funding:
  • Added .github/funding.yml to display a sponsor button in GitHub.
  • Added a package.json funding field to enable npm CLI funding features.

Patch

• Updated dev dependencies.
• Replaced the size-limit dev dependency with @size-limit/preset-small-lib.
• Added a new babel-plugin-transform-require-extensions dev dependency and ensured ESM import specifiers in both source and published .mjs files contain file names with extensions, which are mandatory in the final Node.js ESM implementation. Published CJS .js files now also have file extensions in require paths.
• Added a package module field.
• Removed now redundant ESLint disable require-jsdoc comments.
• Use GitHub Actions instead of Travis for CI.
• Redid the test scripts and enforced 100% code coverage.
• Run size limit tests last in the package test script as they are the slowest.
• Only size limit test the ESM build.
• Updated the package test:tap script to workaround a tap bug.
• Simplified the prepublishOnly script.
• Ordered plugins before presets in Babel config as they run first.
• Reduced the size of the published package.json by moving dev tool config to files.
• Only target the root lib directory in .gitignore and .eslintignore.
• Removed package-lock.json from .gitignore and .prettierignore as it’s disabled in .npmrc anyway.
• Prevented ESLint from ignoring dotfiles.
• Clarified that Opera Mini isn’t supported in the Browserslist queries and readme “Support” section.